Agent Skill 深度指南：Claude Code 模块化能力标准
〇、概述与定位
什么是 Agent Skill？
Agent Skill（又称 Claude Skill）是 Anthropic 推出的一种基于文件系统的模块化能力标准。它本质上是一种"渐进式披露"（Progressive Disclosure）的提示词管理机制，用于解决传统 System Prompt 的效率与可维护性问题。
解决的核心痛点
| 传统方案 | 问题 | Agent Skill 解决方式 |
|---|---|---|
| 单一长 System Prompt | Token 浪费、上下文污染 | 分层加载，按需读取 |
| 硬编码指令 | 难以复用、版本混乱 | 文件系统管理，模块化封装 |
| 能力无边界 | 模型混淆、执行不精准 | 明确触发条件与执行边界 |
生态兼容性
Agent Skill 正在成为 AI 编程工具的事实标准：
| 工具 | 支持状态 | 备注 |
|---|---|---|
| Claude Code | ✅ 原生支持 | Anthropic 官方实现 |
| Cursor | ✅ 支持 | 通过 .cursorrules 或 Skills 目录 |
| Codex CLI | ✅ 支持 | OpenAI 的命令行编程助手 |
| OpenCode | ✅ 支持 | 开源 AI 编程工具 |
| Windsurf | ⚠️ 部分支持 | 通过自定义规则文件 |
一、核心概念：三层架构模型
1.1 核心比喻：一本"带目录的书"
传统的 System Prompt 将所有规则一次性注入 AI，既浪费 Token 又容易造成模型混淆。Agent Skill 采用分层管理策略：
text
┌─────────────────────────────────────────────────────────────────┐
│ Agent Skill 架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 第1层：元数据 (Metadata) ≈ 书的目录 │ │
│ │ ──────────────────────────────────────────────────────── │ │
│ │ • 内容：name + description │ │
│ │ • 加载：✅ 始终加载（启动时） │ │
│ │ • Token：极低消耗（约 50-100 tokens/skill） │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ 匹配触发 │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 第2层：指令 (Instructions) ≈ 书的正文 │ │
│ │ ──────────────────────────────────────────────────────── │ │
│ │ • 内容：Prompt、操作步骤、约束条件 │ │
│ │ • 加载：⚡ 按需加载（触发时） │ │
│ │ • Token：中等消耗（根据指令复杂度） │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ 执行引用 │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 第3层：资源 (Resources) ≈ 书的附录 │ │
│ │ ──────────────────────────────────────────────────────── │ │
│ │ • 内容：scripts/、templates/、assets/ │ │
│ │ • 加载：📂 按需调用（指令执行时） │ │
│ │ • Token：仅在使用时计入 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
1.2 各层详细说明
第1层：元数据 (Metadata)
---
name: csv-data-summarizer
description: 使用 Python 和 pandas 分析 CSV 文件，生成统计摘要并绘制可视化图表。
metadata:
version: 2.1.0
author: your-name
dependencies: python>=3.8, pandas>=2.0.0
---
| 字段 | 必填 | 说明 |
|---|---|---|
name |
✅ 是 | 技能唯一标识符，建议使用 kebab-case |
description |
✅ 是 | 关键字段：Claude 根据此描述判断是否触发技能 |
metadata.version |
否 | 版本号，便于追踪更新 |
metadata.dependencies |
否 | 依赖声明，用于环境检查 |
⚠️ 关键提示：
description的质量直接决定触发精准度。应使用具体、可匹配的关键词，避免模糊表述。
第2层：指令 (Instructions)
位于 SKILL.md 的 Frontmatter 下方，使用 Markdown 格式编写：
# CSV Data Summarizer
## When to Use (触发时机)
当用户满足以下条件时使用此 Skill：
- 上传或引用了一个 CSV 文件
- 要求对表格数据进行摘要、分析或可视化
## Critical Behavior (核心行为准则)
⚠️ **绝对准则**：
1. 禁止询问用户意图，直接执行分析
2. 自动生成所有相关图表
...
第3层：资源 (Resources)
📂 skill-name/
├── 📄 SKILL.md
├── 📂 scripts/ # 可执行脚本
│ ├── analyze.py
│ └── visualize.py
├── 📂 templates/ # 输出模板
│ └── report_format.md
├── 📂 assets/ # 静态资源
│ └── logo.png
└── 📂 examples/ # Few-shot 示例
└── sample_input.csv
1.3 与 MCP 的协作关系
| 组件 | 职责 | 类比 |
|---|---|---|
| Agent Skill | 定义 SOP（标准作业程序）：何时做、怎么做 | 操作手册 |
| MCP (Model Context Protocol) | 提供工具接口：文件读写、API 调用、命令执行 | 工具箱 |
用户请求 → Skill 匹配 → 加载指令 → 调用 MCP 工具 → 执行任务 → 返回结果
二、配置指南：从零开始
2.1 前置条件
- ✅ 已安装 Claude Code（
npm install -g @anthropic-ai/claude-code或官方安装方式） - ✅ 已完成基础配置（API Key 或模型代理）
- ✅ 了解基本的终端操作
2.2 第一步：建立技能库目录
Claude Code 启动时自动扫描以下路径：
| 操作系统 | 路径 |
|---|---|
| Windows | C:\Users\<用户名>\.claude\skills\ |
| macOS/Linux | ~/.claude/skills/ |
标准目录结构：
~/.claude/skills/ # 技能库根目录
│
├── 📂 pdf-summary/ # 技能包 1
│ ├── 📄 SKILL.md # 🔴 必需：技能定义文件（必须大写）
│ ├── 📂 scripts/ # 可执行脚本
│ │ └── 🐍 extract.py
│ └── 📂 templates/ # 输出模板
│ └── 📄 format.txt
│
├── 📂 git-automator/ # 技能包 2
│ └── 📄 SKILL.md
│
└── 📂 code-reviewer/ # 技能包 3
├── 📄 SKILL.md
└── 📂 examples/
└── 📄 review_samples.md
命名规范：
- 技能包文件夹：使用
kebab-case（如pdf-summary） - SKILL.md：必须全大写
SKILL.md - 脚本文件：使用
snake_case（如extract_text.py）
2.3 第二步：编写 SKILL.md
完整模板
---
# ════════════════════════════════════════════════════════════════
# 第1层：元数据区 (Metadata)
# 作用：Claude 启动时只读取这部分，用于判断是否触发此技能
# ════════════════════════════════════════════════════════════════
name: csv-data-summarizer
description: |
使用 Python 和 pandas 分析 CSV 文件，生成统计摘要并绘制快速可视化图表。
支持：数据清洗、缺失值分析、分布统计、相关性热力图。
metadata:
version: 2.1.0
author: your-name
dependencies:
- python>=3.8
- pandas>=2.0.0
- matplotlib>=3.5.0
tags:
- data-analysis
- visualization
- csv
---
# CSV Data Summarizer
<!-- ════════════════════════════════════════════════════════════════
第2层：指令区 (Instructions)
作用：技能被触发后，Claude 遵循这些规则执行任务
════════════════════════════════════════════════════════════════ -->
## 📌 When to Use (触发时机)
当用户满足以下**任一**条件时使用此 Skill：
- 上传或引用了一个 CSV 文件
- 要求对表格数据进行摘要、分析或可视化
- 想要了解数据的结构和质量
- 提及关键词：数据分析、表格处理、统计摘要
## ⚠️ Critical Behavior (核心行为准则)
### 绝对禁止
1. ❌ **禁止询问用户意图**：不要问"你想让我做什么？"或提供选项菜单
2. ❌ **禁止部分执行**：必须完成完整的分析流程
3. ❌ **禁止忽略错误**：遇到数据问题必须报告，而非静默跳过
### 必须执行
1. ✅ **立即全量分析**：自动运行分析、生成所有相关图表
2. ✅ **智能适配**：根据数据内容（销售、客户、财务等）自动决定分析方向
3. ✅ **结果可视化**：至少生成 2 种图表（分布图 + 相关性/趋势图）
## 🔄 Automatic Steps (自动化步骤)
步骤 1: 加载与检查
├── 读取 CSV 到 pandas DataFrame
├── 检查编码（UTF-8/GBK 自动识别）
└── 报告行数、列数
步骤 2: 结构识别
├── 自动判断列类型（日期、数值、分类）
├── 识别主键候选列
└── 检测数据质量问题
步骤 3: 执行分析
├── 数值列：统计描述（均值、中位数、标准差）
├── 分类列：频率分布
├── 日期列：时间范围、趋势
└── 相关性：数值列间的相关矩阵
步骤 4: 生成输出
├── 文本摘要：一段话概述数据特征
├── 统计表格：关键指标汇总
├── 可视化：分布图 + 热力图/趋势图
└── 问题报告：缺失值、异常值警告
## 📋 Output Format (输出格式)
```markdown
## 📊 数据概览
- 文件：{filename}
- 行数：{rows} | 列数：{columns}
- 时间范围：{date_range}（如适用）
## 📈 统计摘要
| 列名 | 类型 | 非空率 | 均值/众数 | 范围/类别数 |
|------|------|--------|-----------|-------------|
| ... | ... | ... | ... | ... |
## ⚠️ 数据质量警告
- {warning_1}
- {warning_2}
## 📉 可视化
[生成的图表将在此展示]
<!-- ════════════════════════════════════════════════════════════════ 第3层：资源区 (Resources) 作用：列出此 Skill 需要调用的文件 ════════════════════════════════════════════════════════════════ -->
Files
核心脚本
scripts/analyze.py - 核心分析逻辑，包含数据清洗和统计函数
scripts/visualize.py - 图表生成模块
配置文件
config/default_settings.json - 默认分析参数
示例资源
examples/sample_sales.csv - 销售数据示例
examples/expected_output.md - 期望输出参考
#### 简化模板（快速上手）
```markdown
---
name: quick-translator
description: 将文本翻译为指定语言，支持中英日韩法德西等主流语言。
---
# Quick Translator
## When to Use
用户请求翻译文本时触发。
## Behavior
1. 自动检测源语言
2. 翻译为用户指定的目标语言（默认：英文）
3. 保持原文格式和语气
## Output
提供：翻译结果 + 源语言识别 + 置信度评分
2.4 第三步：加载与验证
重启 Claude Code
# 关闭当前会话，重新启动
claude
验证加载状态
方法 1：使用 /doctor 命令
> /doctor
输出中会显示已加载的 Skills 列表。
方法 2：直接询问
> 你现在加载了哪些 skills？列出它们的名称和描述。
方法 3：检查特定技能
> 你能处理 CSV 文件分析吗？如果能，是通过哪个 skill 实现的？
2.5 第四步：触发使用
无需特殊命令，直接使用自然语言：
> 帮我分析一下桌面上的 sales_2024.csv，我想看销售趋势
Claude 会：
- 匹配
description中的关键词 → 命中csv-data-summarizer - 加载 SKILL.md 的指令区
- 按照 Automatic Steps 执行
- 调用
scripts/analyze.py（如需要） - 返回结构化结果
三、高级配置与技巧
3.1 多 Skill 协作
当一个任务需要多个 Skill 配合时：
---
name: report-generator
description: 生成完整的数据分析报告，包含数据处理、可视化和 PPT 导出。
metadata:
requires: # 声明依赖的其他 Skills
- csv-data-summarizer
- pptx-creation
---
# Report Generator
## Workflow
1. 调用 `csv-data-summarizer` 分析数据
2. 整理分析结果
3. 调用 `pptx-creation` 生成演示文稿
3.2 条件触发优化
使用负向条件避免误触发：
## When NOT to Use
- 用户只是询问 CSV 格式说明（不涉及具体文件）
- 用户要求手动编辑 CSV（非分析任务）
- 文件大小超过 100MB（应建议使用专业工具）
3.3 Few-Shot 示例增强
在 examples/ 目录中提供示例，提升执行精准度：
# Examples
## 示例 1：销售数据分析
**用户输入**：分析这个销售表格
**期望输出**：[见 examples/sales_output.md]
## 示例 2：客户数据清洗
**用户输入**：帮我清理客户名单里的重复项
**期望输出**：[见 examples/cleanup_output.md]
3.4 错误处理指令
## Error Handling
### 文件不存在
⚠️ 错误：找不到文件 {filename} 请检查：
- 文件路径是否正确
- 文件是否有读取权限
### 格式不支持
⚠️ 错误：不支持的文件格式 {extension} 此 Skill 仅支持：.csv, .tsv, .txt (制表符分隔)
四、安全与权限管理
4.1 安全风险警示
⚠️ 重要警告：Agent Skill 的
scripts/目录可包含任意可执行代码。从不受信任的来源下载 Skill 存在安全风险。
风险矩阵
| 风险类型 | 危害程度 | 防护措施 |
|---|---|---|
| 恶意脚本执行 | 🔴 严重 | 审查所有 scripts/ 文件 |
| 数据外泄 | 🔴 严重 | 检查网络请求代码 |
| 文件系统破坏 | 🟠 中等 | 使用版本控制，定期备份 |
| 依赖投毒 | 🟠 中等 | 验证 requirements.txt 来源 |
4.2 安全审查清单
在使用第三方 Skill 前，执行以下检查：
## 第三方 Skill 安全审查清单
### 基础检查
- [ ] 来源是否可信（官方仓库/知名作者）
- [ ] 是否有 README 说明其功能
- [ ] 社区反馈如何（Star/Issue）
### 代码审查
- [ ] scripts/ 目录下有哪些文件？
- [ ] 是否存在网络请求（requests/urllib）？
- [ ] 是否存在文件删除/修改操作（os.remove/shutil）？
- [ ] 是否存在 subprocess/os.system 调用？
### 权限检查
- [ ] 是否要求管理员/root 权限？
- [ ] 是否访问敏感目录（~/.ssh, ~/.aws）？
4.3 权限模式详解
默认模式（推荐）
每次执行敏感操作前，Claude 会请求确认：
Claude: 我需要运行 scripts/analyze.py 来分析这个 CSV 文件。
是否允许？[y/n]
完全自主模式
claude --dangerously-skip-permissions
| 特性 | 说明 |
|---|---|
| 效果 | Claude 可直接执行所有操作，无需确认 |
| 风险 | 可能意外修改/删除文件、安装未知依赖、执行危险命令 |
| 适用场景 | ① 完全信任的任务环境 ② 代码已提交 Git（可回滚） ③ 在沙盒/容器中运行 |
安全建议：
# 更安全的使用方式：在 Git 仓库中使用，便于回滚
cd your-project
git add -A && git commit -m "checkpoint before claude"
claude --dangerously-skip-permissions
# 任务完成后检查变更
git diff
五、实战案例：完整 Skill 库示例
5.1 目录结构总览
~/.claude/skills/
│
├── 📂 pptx-creation/ # 【Skill 1】PPT 演示文稿生成
│ ├── 📄 SKILL.md
│ ├── 📂 scripts/
│ │ └── 🐍 generate_slides.py # 使用 python-pptx 生成 PPT
│ └── 📂 assets/
│ ├── 📊 corporate_template.pptx # 公司模板
│ └── 📄 layout_config.json # 布局配置
│
├── 📂 xlsx-analysis/ # 【Skill 2】Excel 数据分析
│ ├── 📄 SKILL.md
│ ├── 📂 scripts/
│ │ ├── 🐍 clean_data.py # 数据清洗
│ │ └── 🐍 create_pivot.py # 透视表生成
│ └── 📂 examples/
│ ├── 📄 prompt_examples.txt # Few-shot 示例
│ └── 📉 sample_output.xlsx # 输出参考
│
├── 📂 git-workflow/ # 【Skill 3】Git 操作自动化
│ ├── 📄 SKILL.md
│ └── 📂 scripts/
│ ├── 🔧 smart_commit.sh # 智能提交信息生成
│ └── 🔧 pr_template.sh # PR 描述生成
│
├── 📂 api-tester/ # 【Skill 4】API 测试助手
│ ├── 📄 SKILL.md
│ ├── 📂 scripts/
│ │ └── 🐍 request_builder.py # 请求构造器
│ └── 📂 templates/
│ └── 📄 report_template.md # 测试报告模板
│
└── 📂 doc-generator/ # 【Skill 5】文档生成器
├── 📄 SKILL.md
└── 📂 templates/
├── 📄 api_doc.md # API 文档模板
├── 📄 readme.md # README 模板
└── 📄 changelog.md # 更新日志模板
5.2 示例 Skill：Git 工作流自动化
---
name: git-workflow
description: |
自动化 Git 工作流：智能生成 commit 信息、创建规范的 PR 描述、
分析代码变更并建议版本号更新。
metadata:
version: 1.0.0
dependencies:
- git>=2.30
---
# Git Workflow Automator
## When to Use
- 用户完成代码修改，准备提交
- 用户请求生成 commit 信息
- 用户准备创建 Pull Request
- 用户询问应该使用什么版本号
## Commit Message Generation
### 规范
遵循 Conventional Commits 规范：
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
### Types
- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档变更
- `style`: 代码格式（不影响逻辑）
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具变更
### 流程
1. 运行 `git diff --staged` 分析变更
2. 识别变更类型和范围
3. 生成符合规范的 commit 信息
4. 询问用户确认或修改
## PR Description Generation
### 模板
```markdown
## 变更概述
{一句话描述此 PR 的目的}
## 变更类型
- [ ] 新功能
- [ ] Bug 修复
- [ ] 重构
- [ ] 文档更新
## 变更详情
{逐条列出主要修改}
## 测试说明
{如何验证这些变更}
## 相关 Issue
Closes #{issue_number}
Files
scripts/smart_commit.sh - 分析 git diff 并生成 commit 信息
scripts/pr_template.sh - 生成 PR 描述
六、常见问题排查
Q1：Skill 没有被加载
排查步骤：
检查路径是否正确
└── ~/.claude/skills/<skill-name>/SKILL.md
检查文件名是否大写
└── 必须是 SKILL.md，不是 skill.md
检查 Frontmatter 格式
└── 必须以 --- 开头和结尾
└── YAML 语法是否正确（缩进、冒号后空格）
重启 Claude Code
└── 关闭终端，重新运行 claude
Q2：Skill 加载了但不触发
可能原因：
description与用户输入的关键词不匹配- 存在其他 Skill 的
description更匹配
解决方案：
- 优化
description，使用更具体的关键词 - 添加
When to Use部分的详细触发条件 - 测试时明确提及 Skill 名称："使用 csv-data-summarizer 分析这个文件"
Q3：脚本执行失败
排查清单：
- Python 版本是否满足 dependencies 要求
- 所需库是否已安装（
pip install -r requirements.txt） - 脚本是否有执行权限（Linux/macOS：
chmod +x script.py） - 脚本路径在 SKILL.md 中是否正确声明
Q4：如何调试 Skill 逻辑
# 方法 1：要求 Claude 显示推理过程
> 请分析这个 CSV 文件，并详细说明你调用了哪个 skill、执行了哪些步骤
# 方法 2：检查 skill 匹配
> 如果我说"帮我做个销售报表"，你会触发哪个 skill？为什么？
# 方法 3：手动测试脚本
cd ~/.claude/skills/csv-data-summarizer/scripts
python analyze.py test_data.csv
七、资源与参考
官方资源
| 资源 | 链接 |
|---|---|
| Claude Code 文档 | https://docs.anthropic.com/claude-code |
| Anthropic 官方 Skills | https://github.com/anthropics/skills |
| MCP 协议规范 | https://modelcontextprotocol.io |
社区资源
| 资源 | 说明 |
|---|---|
| awesome-claude-skills | GitHub 上的社区 Skill 集合 |
| r/ClaudeAI | Reddit 讨论社区 |
推荐学习路径
1. 入门：使用官方示例 Skill，理解结构
↓
2. 实践：基于模板创建自己的简单 Skill
↓
3. 进阶：添加 scripts/ 实现复杂逻辑
↓
4. 高级：多 Skill 协作 + MCP 工具集成
八、快速参考卡片
SKILL.md 结构速查
┌─────────────────────────────────────────────────┐
│ SKILL.md 标准结构 │
├─────────────────────────────────────────────────┤
│ --- │
│ name: skill-name # 必填 │
│ description: ... # 必填，决定触发 │
│ metadata: # 可选 │
│ version: x.x.x │
│ dependencies: [...] │
│ --- │
│ │
│ # Skill Title │
│ ## When to Use # 触发条件 │
│ ## Critical Behavior # 核心行为 │
│ ## Automatic Steps # 执行步骤 │
│ ## Output Format # 输出格式 │
│ ## Error Handling # 错误处理 │
│ │
│ # Files # 资源声明 │
│ - scripts/xxx.py │
│ - templates/xxx.md │
└─────────────────────────────────────────────────┘
目录结构速查
~/.claude/skills/
└── skill-name/ # kebab-case 命名
├── SKILL.md # 🔴 必需，大写
├── scripts/ # 可执行脚本
├── templates/ # 输出模板
├── assets/ # 静态资源
└── examples/ # Few-shot 示例
安全检查速查
第三方 Skill 使用前：
├── ✅ 检查来源可信度
├── ✅ 审查 scripts/ 下所有代码
├── ✅ 检查是否有网络请求
├── ✅ 检查是否有文件操作
└── ✅ 在沙盒/Git 环境中首次测试
持续更新提示：Agent Skill 标准仍在快速演进中。建议关注：
- Anthropic 官方博客
- Claude Code Release Notes
- GitHub anthropics/skills 仓库更新
💬 评论